home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.103 < prev    next >
Encoding:
Text File  |  1991-11-15  |  3.6 KB  |  128 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIgs
  8. #103:        Inline Procedure Name Format
  9.  
  10. Written by:  Dave Lyons                                         December 1991
  11.  
  12. This Technical Note describes a simple format for imbedding procedure names in
  13. object code, for use by debugging utilities.
  14. _____________________________________________________________________________
  15.  
  16.  
  17. GSBug 1.5b18 and later support a simple convention for including procedure
  18. names inline in the object code, for debugging purposes.
  19.  
  20.  
  21. Inline Name Format
  22.  
  23. 82 xx xx                            brl  pastName
  24. 71 77                               dc.w $7771
  25. nn xx xx xx xx...                   str  'the name string'
  26.                        pastName     ...
  27.  
  28. That is, an imbedded name is a BRL around a signature word and a Pascal string.
  29. The name string can theoretically be up to 255 characters long, but in practice
  30. only short names are useful.  For example, GSBug displays only the first 15
  31. characters of a name when it is encountered, and only the first 11 when it
  32. appears as the operand of a JSR or JSL instruction.
  33.  
  34. Names in this format always start with a BRL, not a BRA or JMP.  Signature word
  35. values other than $7771 are reserved for future definition, as is the space
  36. after the Pascal string.
  37.  
  38. Be careful what you name!
  39.  
  40. Be careful not to name something important--like a table, or a label from which
  41. you compute other addresses.  The extra bytes generated by the inline name
  42. would mess up your calculations.  If you name a heartbeat task, out-of-memory
  43. queue routine, or other construction that needs a special header, be sure to
  44. put the name where the executable code starts, not at the beginning of the
  45. header.
  46.  
  47. APW Assembly Macro
  48.  
  49. The following macro is for the APW assembler.  If you equate DebugSymbols to
  50. zero, the macro generates no object code.  If DebugSymbols is nonzero, the
  51. macro generates an inline name corresponding to its label.
  52.  
  53. Use the name macro anywhere you would use a label.  For example:
  54.  
  55. DebugSymbols   GEQU 1
  56. ...
  57. CountItems     name
  58.  
  59. The macro:
  60.  
  61.      MACRO
  62. &lab name
  63. &lab anop
  64.      aif DebugSymbols=0,.pastName
  65.      brl pastName&syscnt
  66.      dc i'$7771'
  67.      dc i1'L:&lab',c'&lab'
  68. pastName&syscnt anop
  69. .pastName
  70.      MEND
  71.  
  72.  
  73. MPW IIgs Assembly Macros
  74.  
  75. The following macros are for the MPW IIgs assembler.  If you equate
  76. DebugSymbols to zero, the macros generate no object code.  If DebugSymbols is
  77. nonzero, the macros generate inline names corresponding to their labels.
  78.  
  79. Use the name macro anywhere you would use a label.  Use the procname macro in
  80. place of a proc directive, at the beginning of a procedure.  For example:
  81.  
  82. DebugSymbols    equ 1
  83. ...
  84. CountItems    name
  85. TaskLoop    procname
  86.  
  87. The macros:
  88.  
  89.     macro
  90. &lab name
  91. &lab
  92.     if DebugSymbols<>0 then
  93.     brl @pastName
  94.     lclc &olds
  95. &olds    setc &setting('string')
  96.     string asis
  97.     dc.w $7771
  98.     dc.b &len(&lab),'&lab'
  99.     string &olds
  100. @pastName
  101.     endif
  102.     mend
  103.  
  104. * You can use procname instead of proc
  105.  
  106.     macro
  107. &lab procname &x
  108. &lab proc &x
  109.     if DebugSymbols<>0 then
  110.     brl @pastName
  111.     lclc &olds
  112. &olds setc &setting('string')
  113.     string asis
  114.     dc.w $7771
  115.     dc.b &len(&lab),'&lab'
  116.     string &olds
  117. @pastName
  118.     endif
  119.     mend
  120.  
  121. Writing utilities that recognize inline names
  122.  
  123. If you write a utility that recognizes inline procedure names in this format,
  124. check for a signature word of $777x, not specifically $7771.  This allows more
  125. information to be added to the format later (a signature of $7772 could mean
  126. there is a Pascal string followed by parameter-passing information, for
  127. example).
  128.